home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / Reference / DevCon / Orlando_1993 / Devcon93.4 / CAMD / docs / realtime.autodoc < prev    next >
Encoding:
Text File  |  1993-01-12  |  10.6 KB  |  342 lines
  1. TABLE OF CONTENTS
  2.  
  3. realtime.library/CreatePlayer
  4. realtime.library/DeletePlayer
  5. realtime.library/ExternalSync
  6. realtime.library/FindConductor
  7. realtime.library/GetPlayerAttrA
  8. realtime.library/LockRealTime
  9. realtime.library/NextConductor
  10. realtime.library/SetConductorState
  11. realtime.library/SetPlayerAttrs
  12. realtime.library/UnlockRealTime
  13. realtime.library/CreatePlayer                     realtime.library/CreatePlayer
  14.  
  15.    NAME
  16.        CreatePlayer -- Create a PlayerInfo and link to a Conductor.
  17.  
  18.    SYNOPSIS
  19.        struct PlayerInfo *CreatePlayerA (struct TagItem *TagsList)
  20.                                                a0
  21.  
  22.        struct PlayerInfo *CreatePlayer (Tag tag1, ...)
  23.  
  24.    FUNCTION
  25.        Creates a PlayerInfo structure with the desired attributes.
  26.  
  27.        The first form of the function expects a tag array pointer or NULL.
  28.        The second form permits the tag items to exist on the caller's
  29.        stack.  In both cases, the final tag item must be TAG_END.
  30.  
  31.    INPUTS
  32.        TagList   - optional pointer to tag array.  May be NULL.  For
  33.                    OS v1.3, there are restrictions on the tag array
  34.                    contents.  See NOTE below.
  35.  
  36.    TAGS
  37.         See SetPlayerAttrsA()
  38.  
  39.    RESULTS
  40.        A pointer to a PlayerInfo structure on success or NULL on failure.
  41.        When NULL is returned, an error code will be returned if a TagItem
  42.         with an ti_Tag of PLAYER_ErrorCode was provided. The RTE_ error code
  43.         will be put in the ti_Data field.
  44.  
  45.    NOTE
  46.        Under 1.3 only a restricted tag array may be passed into this
  47.        function. The only special tag values that are supported are those
  48.         documented for Release 2.04. The full range of TAG list operations
  49.         are permitted under 2.0.
  50.  
  51.    EXAMPLES
  52.        pi = CreatePlayer (
  53.                PLAYER_Conductor, "metric", PLAYER_Priority, 10, TAG_END);
  54.  
  55.    SEE ALSO
  56.        DeletePlayer(), SetPlayerAttrs()
  57.        2.0 tag docs.
  58. realtime.library/DeletePlayer                     realtime.library/DeletePlayer
  59.  
  60.    NAME
  61.        DeletePlayer -- Delete a PlayerInfo structure
  62.  
  63.    SYNOPSIS
  64.        void DeletePlayer (struct PlayerInfo *pi)
  65.                                a0
  66.  
  67.    FUNCTION
  68.        Deletes the specified PlayerInfo. The following actions are
  69.         automatically performed by this function:
  70.  
  71.         Flushes the Conductor that the PlayerInfo was connected to if this
  72.         is the last PlayerInfo connected to that Conductor.
  73.  
  74.    INPUTS
  75.        pi - PlayerInfo to delete. Can be NULL.
  76.  
  77.    RESULTS
  78.        None
  79.  
  80.    SEE ALSO
  81.        CreatePlayer()
  82. realtime.library/ExternalSync                     realtime.library/ExternalSync
  83.  
  84.    NAME
  85.        ExternalSync -- External source clock for a PlayerInfo's Conductor
  86.  
  87.    SYNOPSIS
  88.        BOOL ExternalSync (struct PlayerInfo *pi, LONG mintime,
  89.                                a0                       d0
  90.                 LONG maxtime)
  91.                 d1
  92.  
  93.    FUNCTION
  94.        Allows external application to constrain conductor time between
  95.         mintime and maxtime, with the restraint that time can never run
  96.         backwards. Does nothing if the given PlayerInfo is not the
  97.         current External Sync source (as indicated by the PLAYERF_EXTSYNC
  98.         flag).
  99.  
  100.    INPUTS
  101.        pi - PlayerInfo referencing the Conductor to change
  102.         mintime, maxtime - time constraints
  103.  
  104.    RESULTS
  105.        result - TRUE if everything went OK, FALSE if not the current sync
  106.            source or no conductor
  107.  
  108. realtime.library/FindConductor                   realtime.library/FindConductor
  109.  
  110.    NAME
  111.        FindConductor -- Find a conductor by name
  112.  
  113.    SYNOPSIS
  114.        struct Conductor *FindConductor (char *name)
  115.                                          a0
  116.  
  117.    FUNCTION
  118.        Returns the Conductor with the given name or NULL.
  119.         Conductor links (CD_Conductors) must be locked when called.
  120.  
  121.    INPUTS
  122.        name - name of conductor to find
  123.  
  124.    RESULTS
  125.        result - Conductor or NULL
  126.  
  127. realtime.library/GetPlayerAttrA                 realtime.library/GetPlayerAttrA
  128.  
  129.    NAME
  130.        GetPlayerAttrA -- Set the attributes of a PlayerInfo
  131.  
  132.    SYNOPSIS
  133.        ULONG GetPlayerAttrA (struct PlayerInfo *pi, struct TagItem *attrs)
  134.                                        a0          a1
  135.  
  136.    FUNCTION
  137.        Get attributes of a PlayerInfo.
  138.  
  139.    INPUTS
  140.        pi - a pointer to the PlayerInfo
  141.  
  142.        attrs - Attributes to get, terminated with TAG_DONE.  The data
  143.            element of each pair contains the address of the storage
  144.            variable.
  145.  
  146.    RESULTS
  147.         Count of attributes understood.
  148.  
  149.    NOTE
  150.         Not implemented yet. Does nothing at this time.
  151.  
  152.    EXAMPLES
  153.  
  154.    SEE ALSO
  155.        SetPlayerAttrs()
  156. realtime.library/LockRealTime                     realtime.library/LockRealTime
  157.  
  158.    NAME
  159.        LockRealTime -- Prevent other tasks from changing internal structures
  160.  
  161.    SYNOPSIS
  162.        LockRealTime(locktype)
  163.             d0
  164.        APTR LockRealTime( ULONG );
  165.  
  166.    FUNCTION
  167.        This routine will lock the internal sempahores in the RealTime library.
  168.        If they are already locked by another task, this routine will wait
  169.         until they are free.
  170.  
  171.    INPUTS
  172.        locktype -- which internal list will be locked.
  173.            RT_Conductors -- locks the internal list of Conductors and
  174.                 associated structures.
  175.  
  176.    RESULT
  177.        If locktype is valid, returns a value that must be passed later
  178.         to UnlockRealTime.
  179.  
  180.    EXAMPLE
  181.  
  182.    NOTES
  183.  
  184.    BUGS
  185.  
  186.    SEE ALSO
  187.        UnlockRealTime()
  188.  
  189. realtime.library/NextConductor                   realtime.library/NextConductor
  190.  
  191.    NAME
  192.        NextConductor -- Return next Conductor on RealTime Conductor list
  193.  
  194.    SYNOPSIS
  195.        struct Conductor *NextConductor (struct Conductor *last)
  196.                                          a0
  197.  
  198.    FUNCTION
  199.        Returns the next Conductor on RealTime Conductor list. If last is NULL,
  200.         returns the first Conductor. Returns NULL if no more Conductors.
  201.         Conductor links (RT_Conductors) must be locked when called.
  202.  
  203.    INPUTS
  204.        last - previous Conductor or NULL to get first Conductor
  205.  
  206.    RESULTS
  207.        next - next Conductor or NULL
  208.  
  209. realtime.library/SetConductorState           realtime.library/SetConductorState
  210.  
  211.    NAME
  212.        SetConductorState -- Change the play state of a PlayerInfo's conductor
  213.  
  214.    SYNOPSIS
  215.        LONG SetConductorState (struct PlayerInfo *pi, LONG state, LONG time)
  216.                                a0                       d0          d1
  217.  
  218.    FUNCTION
  219.        Changes the play state of the Conductor referenced by the
  220.         PlayerInfo. The states can be CLOCKSTATE_STOPPED, CLOCKSTATE_PAUSED,
  221.         CLOCKSTATE_LOCATE, CLOCKSTATE_RUNNING, or the special value
  222.         CLOCKSTATE_METRIC which asks the highest priority conducted node
  223.         to do a CLOCKSTATE_LOCATE, or the special value CLOCKSTATE_SHUTTLE
  224.         which informs the players that the clock value is changing, but the
  225.         clock isn't actually running. Note that going from CLOCKSTATE_PAUSED
  226.         to CLOCKSTATE_RUNNING does not reset the ClockTime of the Conductor.
  227.  
  228.  
  229.    INPUTS
  230.        pi - PlayerInfo referencing the Conductor to change
  231.         state - new play state of Conductor
  232.         time - start time offset in RealTime heartbeat units
  233.  
  234.    RESULTS
  235.        result - 0 if everything went OK, else an error code
  236. realtime.library/SetPlayerAttrs                 realtime.library/SetPlayerAttrs
  237.  
  238.    NAME
  239.        SetPlayerAttrs -- Set the attributes of a PlayerInfo
  240.  
  241.    SYNOPSIS
  242.        BOOL SetPlayerAttrsA (struct PlayerInfo *pi, struct TagItem *tags)
  243.                                        a0          a1
  244.  
  245.        BOOL SetPlayerAttrs (struct PlayerInfo *pi, ...)
  246.  
  247.    FUNCTION
  248.        Sets the attributes of a PlayerInfo, using a Tag List.
  249.  
  250.        The first form of the function expects a tag array pointer or NULL.
  251.        The second form permits the tag items to exist on the caller's
  252.        stack.  In both cases, the final tag item must be TAG_END.
  253.  
  254.    INPUTS
  255.        pi - a pointer to the PlayerInfo structure
  256.  
  257.        TagList   - optional pointer to tag array.  May be NULL.  For
  258.                    OS v1.3, there are restrictions on the tag array
  259.                    contents.  See NOTE below.
  260.  
  261.    TAGS
  262.        PLAYER_Name         STRPTR - ti_Data points to the new name of
  263.                    the PlayerInfo (generally the Application name)
  264.  
  265.        PLAYER_Hook         struct Hook * - this hook will be called when
  266.                    time changes occur.
  267.  
  268.        PLAYER_Priority     BYTE - new priority for the PlayerInfo
  269.  
  270.        PLAYER_Conductor    STRPTR - ti_Data points to the name of the
  271.                    Conductor to link with. If NULL, delink from conductor.
  272.                     If ~0, create private conductor.
  273.  
  274.        PLAYER_Ready        BOOL - set/clear the "ready" flag
  275.  
  276.        PLAYER_SignalTask   struct Task * - task to signal on notify or alarm
  277.  
  278.        PLAYER_AlarmSigBit  BYTE - signal bit to use on alarm or
  279.                     -1 to disable
  280.  
  281.        PLAYER_Quiet        BOOL - when TRUE, this node is ignored. Mainly
  282.                     used by external sync applications
  283.  
  284.        PLAYER_UserData     void * - sets UserData field
  285.  
  286.        PLAYER_ID           UWORD - sets PlayerID field
  287.  
  288.        PLAYER_AlarmTime    LONG - sets the AlarmTime and the ALARMSET flag
  289.  
  290.        PLAYER_AlarmOn      BOOL - if TRUE sets the ALARMSET flag, FALSE clears
  291.                     the flag
  292.  
  293.        PLAYER_Conducted    BOOL - if TRUE sets the CONDUCTED flag, FALSE clears
  294.                     the flag
  295.  
  296.        PLAYER_ExtSync      BOOL - attempt to become external sync source (TRUE)
  297.                    or release external sync (FALSE)
  298.  
  299.    RESULTS
  300.        TRUE if all changes were made successfully or FALSE on failure.
  301.        When FALSE is returned, an error code will be returned if a TagItem
  302.         with an ti_Tag of PLAYER_ErrorCode was provided. The RTE_ error code
  303.         will be put in the ti_Data field.
  304.  
  305.    NOTE
  306.        Under 1.3 only a restricted tag array may be passed into this
  307.        function. The only special tag values that are supported are those
  308.         documented for Release 2.04. The full range of TAG list operations
  309.         are permitted under 2.0.
  310.  
  311.    EXAMPLES
  312.        result = SetPlayerAttrs (pi,
  313.                PLAYER_Conductor, "metric", PLAYER_Priority, 10, TAG_END);
  314.  
  315.        Modifies a PlayerInfo to so it links to the Conductor named "metric"
  316.        and sets the priorityof the PlayerInfo to +10.
  317.  
  318.    SEE ALSO
  319.        CreatePlayer(), DeletePlayer()
  320.        2.0 tag docs.
  321. realtime.library/UnlockRealTime                 realtime.library/UnlockRealTime
  322.  
  323.    NAME
  324.        UnlockRealTime -- Unlock internal lists
  325.  
  326.    SYNOPSIS
  327.        UnlockRealTime(lock)
  328.                        a0
  329.        void UnlockRealTime( APTR );
  330.  
  331.    FUNCTION
  332.        Undoes the effects of LockRealTime().
  333.  
  334.    INPUTS
  335.        lock -- value returned by LockRealTime(). Can be NULL.
  336.  
  337.    EXAMPLE
  338.  
  339.    SEE ALSO
  340.        LockRealTime()
  341.  
  342.